</para>
<example>
-<title> Typical <function>main</function> function for a GTK application</title>
+<title>Typical <function>main</function> function for a GTK application</title>
<programlisting>
int
main (int argc, char **argv)
{
/* Initialize i18n support */
- gtk_set_locale ();
+ gtk_set_locale (∅);
/* Initialize the widget set */
gtk_init (&argc, &argv);
gtk_widget_show_all (mainwin);
/* Enter the main event loop, and wait for user interaction */
- gtk_main ();
+ gtk_main (∅);
/* The user lost interest */
return 0;
<function>main</function> function. Changed if any arguments were
handled.
@argv: Address of the <parameter>argv</parameter> parameter of
-<function>main</function>. Any parameters understood by <function>
-gtk_init</function> are stripped before return.
+<function>main()</function>. Any parameters understood by gtk_init()
+are stripped before return.
<!-- ##### FUNCTION gtk_init_check ##### -->
<para>
-This function does the same work as <function>gtk_init</function> with only
+This function does the same work as gtk_init() with only
a single change: It does not terminate the program if the GUI can't be
initialized. Instead it returns %FALSE on failure.
</para>
with the user - for example a curses or command line interface.
</para>
-@argc: A reference to the <parameter>argc</parameter> of the <function>main
-</function> function.
-@argv: A reference to the <parameter>argv</parameter> of the <function>main
-</function> function.
-@Returns: %TRUE if the GUI has been successful initialized,
+@argc: A reference to the <parameter>argc</parameter> of the
+<function>main()</function> function.
+@argv: A reference to the <parameter>argv</parameter> of the
+<function>main()</function> function.
+@Returns: %TRUE if the GUI has been successfully initialized,
%FALSE otherwise.
<!-- ##### FUNCTION gtk_exit ##### -->
<para>
-Terminate the program and return the given exit code to the caller.
+Terminates the program and returns the given exit code to the caller.
This function will shut down the GUI and free all resources allocated
for GTK.
</para>
<!-- ##### FUNCTION gtk_events_pending ##### -->
<para>
-Check if any events are pending. This can be used to update the GUI
+Checks if any events are pending. This can be used to update the GUI
and invoke timeouts etc. while doing some time intensive computation.
</para>
<example>
-<title> Updating the GUI during a long computation</title>
+<title>Updating the GUI during a long computation</title>
<programlisting>
/* computation going on */
...
- while (gtk_events_pending ())
- gtk_main_iteration ();
+ while (gtk_events_pending (∅))
+ gtk_main_iteration (∅);
...
/* computation continued */
</programlisting>
<!-- ##### FUNCTION gtk_main ##### -->
<para>
Runs the main loop until gtk_main_quit() is called. You can nest calls to
-gtk_main. In that case gtk_main_quit() will make the innerst invocation
+gtk_main(). In that case gtk_main_quit() will make the innermost invocation
of the main loop return.
</para>
<!-- ##### FUNCTION gtk_main_level ##### -->
<para>
-Ask for the current nesting level of the main loop. This can be useful
-when calling gtk_quit_add.
+Asks for the current nesting level of the main loop. This can be useful
+when calling gtk_quit_add().
</para>
@Returns: the nesting level of the current invocation of the main loop.
<para>
Runs a single iteration of the mainloop. If no events are waiting to be
processed GTK+ will block until the next event is noticed. If you don't
-want to block look at gtk_main_iteration_do or check if any events are
-pending with gtk_events_pending first.
+want to block look at gtk_main_iteration_do() or check if any events are
+pending with gtk_events_pending() first.
</para>
-@Returns: %TRUE if gtk_main_quit has been called for the innermost mainloop.
+@Returns: %TRUE if gtk_main_quit() has been called for the innermost mainloop.
<!-- ##### FUNCTION gtk_main_iteration_do ##### -->
<para>
-Run a single iteration of the mainloop. If no events are available either
-return or block dependend on the value of @blocking.
+Runs a single iteration of the mainloop. If no events are available either
+return or block dependent on the value of @blocking.
</para>
@blocking: %TRUE if you want GTK+ to block if no events are pending.
-@Returns: %TRUE if gtk_main_quit has been called for the innermost mainloop.
+@Returns: %TRUE if gtk_main_quit() has been called for the innermost mainloop.
<!-- ##### FUNCTION gtk_main_do_event ##### -->
<para>
-Process a single GDK event. This is public only to allow filtering of events
-between GDK and GTK. You will not usually need to call this function directly.
+Processes a single GDK event. This is public only to allow filtering of events
+between GDK and GTK+. You will not usually need to call this function directly.
</para>
<para>
While you should not call this function directly, you might want to know
<orderedlist>
<listitem><para>
Compress enter/leave notify events. If the event passed build an
- enter/leave pair together with the next event (peeked from Gdk)
+ enter/leave pair together with the next event (peeked from GDK)
both events are thrown away. This is to avoid a backlog of (de-)highlighting
widgets crossed by the pointer.
</para></listitem>
<listitem><para>
Find the widget which got the event. If the widget can't be determined
the event is thrown away unless it belongs to a INCR transaction. In that
- case it is passed to gtk_selection_incr_event.
+ case it is passed to gtk_selection_incr_event().
</para></listitem>
<listitem><para>
Then the event is passed on a stack so you can query the currently handled
- event with gtk_get_current_event.
+ event with gtk_get_current_event().
</para></listitem>
<listitem><para>
The event is sent to a widget. If a grab is active all events for
</para></listitem>
</orderedlist>
-@event: An event to process (normally) passed by Gdk.
+@event: An event to process (normally) passed by GDK.
<!-- ##### USER_FUNCTION GtkModuleInitFunc ##### -->
<para>
-Each GTK+ module must have a function gtk_module_init with this prototype.
-This function is called after loading the module with the argc and argv
+Each GTK+ module must have a function gtk_module_init() with this prototype.
+This function is called after loading the module with the @argc and @argv
cleaned from any arguments that GTK+ handles itself.
</para>
-@argc: Pointer to the number of arguments remaining after gtk_init.
+@argc: Pointer to the number of arguments remaining after gtk_init().
@argv: Points to the argument vector.
<!-- ##### FUNCTION gtk_true ##### -->
<para>
-All this function does it to return TRUE. This can be useful for example
+All this function does it to return %TRUE. This can be useful for example
if you want to inhibit the deletion of a window. Of course you should
not do this as the user expects a reaction from clicking the close
icon of the window...
</para>
<example>
-<title> A persistent window</title>
+<title>A persistent window</title>
<programlisting>
##include <gtk/gtk.h>
gtk_container_add (GTK_CONTAINER (win), but);
gtk_widget_show_all (win);
- gtk_main ();
+ gtk_main (∅);
return 0;
}
</programlisting>
<!-- ##### FUNCTION gtk_false ##### -->
<para>
-Analogical to <function>gtk_true</function> this function does nothing
+Analogical to gtk_true() this function does nothing
but always returns %FALSE.
</para>
<!-- ##### FUNCTION gtk_grab_add ##### -->
<para>
-Makes %widget the current grabbed widget. This means that interaction with
+Makes @widget the current grabbed widget. This means that interaction with
other widgets in the same application is blocked and mouse as well as
-keyboard events are delivered to this %widget.
+keyboard events are delivered to this widget.
</para>
@widget: The widget that grabs keyboard and pointer events.
<!-- ##### FUNCTION gtk_grab_remove ##### -->
<para>
-Remove the grab from the given widget. You have to pair calls to gtk_grab_add
-and gtk_grab_remove.
+Removes the grab from the given widget. You have to pair calls to gtk_grab_add()
+and gtk_grab_remove().
</para>
@widget: The widget which gives up the grab.
<!-- ##### FUNCTION gtk_init_add ##### -->
<para>
-Register a function to be called when the mainloop is started.
+Registers a function to be called when the mainloop is started.
</para>
-@function: Function to invoke when gtk_main is called next.
+@function: Function to invoke when gtk_main() is called next.
@data: Data to pass to that function.
<!-- ##### FUNCTION gtk_quit_add_destroy ##### -->
<para>
-Trigger destruction of %object in case the mainloop at level %main_level
+Trigger destruction of @object in case the mainloop at level @main_level
is quit.
</para>
mainloop.
@function: The function to call. This should return 0 to be removed from the
list of quit handlers. Otherwise the function might be called again.
-@data: Pointer to pass when calling %function.
+@data: Pointer to pass when calling @function.
@Returns: A handle for this quit handler (you need this for gtk_quit_remove())
- or 0 if you passed a NULL pointer in %function.
+ or 0 if you passed a %NULL pointer in @function.
<!-- ##### FUNCTION gtk_quit_add_full ##### -->
</para>
<para>
The former can be used to run interpreted code instead of a compiled function
-while the latter can be used to free the information stored in %data (while
-you can do this in %function as well)... So this function will mostly be
+while the latter can be used to free the information stored in @data (while
+you can do this in @function as well)... So this function will mostly be
used by GTK+ wrappers for languages other than C.
</para>
mainloop.
@function: The function to call. This should return 0 to be removed from the
list of quit handlers. Otherwise the function might be called again.
-@marshal: The marshaller to be used. If this is non-NULL, %function is
+@marshal: The marshaller to be used. If this is non-%NULL, @function is
ignored.
-@data: Pointer to pass when calling %function.
-@destroy: Function to call to destruct %data. Gets %data as argument.
+@data: Pointer to pass when calling @function.
+@destroy: Function to call to destruct @data. Gets @data as argument.
@Returns: A handle for this quit handler (you need this for gtk_quit_remove())
- or 0 if you passed a NULL pointer in %function.
+ or 0 if you passed a %NULL pointer in @function.
<!-- ##### FUNCTION gtk_quit_remove ##### -->
<para>
-Remove a quit handler by it's identifier.
+Removes a quit handler by it's identifier.
</para>
@quit_handler_id: Identifier for the handler returned when installing it.
<!-- ##### FUNCTION gtk_quit_remove_by_data ##### -->
<para>
-Remove a quit handler identified by it's %data field.
+Removes a quit handler identified by it's @data field.
</para>
-@data: The pointer passed as %data to gtk_quit_add() or gtk_quit_add_full().
+@data: The pointer passed as @data to gtk_quit_add() or gtk_quit_add_full().
<!-- ##### FUNCTION gtk_timeout_add_full ##### -->
<para>
Registers a function to be called periodically. The function will be called
-repeatedly after %interval milliseconds until it returns %FALSE at which
+repeatedly after @interval milliseconds until it returns %FALSE at which
point the timeout is destroyed and will not be called again.
</para>
@interval: The time between calls to the function, in milliseconds
(1/1000ths of a second.)
@function: The function to call periodically.
-@marshal: The marshaller to use instead of the function (if non-NULL).
+@marshal: The marshaller to use instead of the function (if non-%NULL).
@data: The data to pass to the function.
-@destroy: Function to call when the timeout is destroyed or NULL.
+@destroy: Function to call when the timeout is destroyed or %NULL.
@Returns: A unique id for the event source.
<!-- ##### FUNCTION gtk_timeout_add ##### -->
<para>
Registers a function to be called periodically. The function will be called
-repeatedly after %interval milliseconds until it returns %FALSE at which
+repeatedly after @interval milliseconds until it returns %FALSE at which
point the timeout is destroyed and will not be called again.
</para>
<para>
Causes the mainloop to call the given function whenever no events with
higher priority are to be processed. The default priority is
-GTK_PRIORITY_DEFAULT, which is rather low.
+%GTK_PRIORITY_DEFAULT, which is rather low.
</para>
@function: The function to call.
<para>
Like gtk_idle_add() this function allows you to have a function called
when the event loop is idle. The difference is that you can give a
-priority different from GTK_PRIORITY_DEFAULT to the idle function.
+priority different from %GTK_PRIORITY_DEFAULT to the idle function.
</para>
-@priority: The priority which should not be above G_PRIORITY_HIGH_IDLE.
-Note that you will interfere with GTK if you use a priority above
-GTK_PRIORITY_RESIZE.
+@priority: The priority which should not be above %G_PRIORITY_HIGH_IDLE.
+Note that you will interfere with GTK+ if you use a priority above
+%GTK_PRIORITY_RESIZE.
@function: The function to call.
@data: Data to pass to that function.
@Returns: A unique id for the event source.
<!-- ##### FUNCTION gtk_idle_add_full ##### -->
<para>
-
+Like gtk_idle_add() this function allows you to have a function called
+when the event loop is idle. The difference is that you can give a
+priority different from %GTK_PRIORITY_DEFAULT to the idle function.
</para>
-@priority:
-@function:
-@marshal:
-@data:
-@destroy:
-@Returns:
+@priority: The priority which should not be above %G_PRIORITY_HIGH_IDLE.
+Note that you will interfere with GTK+ if you use a priority above
+%GTK_PRIORITY_RESIZE.
+@function: The function to call.
+@marshal: The marshaller to use instead of the function (if non-%NULL).
+@data: Data to pass to that function.
+@destroy: Function to call when the timeout is destroyed or %NULL.
+@Returns: A unique id for the event source.
<!-- ##### FUNCTION gtk_idle_remove ##### -->
GTK+ so everything running at this priority will be running before anything
inside the toolkit.
<note><para>
-This macro is deprecated. You should use G_PRIORITY_HIGH instead.
+This macro is deprecated. You should use %G_PRIORITY_HIGH instead.
</para></note>
</para>
<para>
Default priority for idle functions.
<note><para>
-This macro is deprecated. You should use G_PRIORITY_DEFAULT_IDLE instead.
+This macro is deprecated. You should use %G_PRIORITY_DEFAULT_IDLE instead.
</para></note>
</para>
<para>
Priority for very unimportant background tasks.
<note><para>
-This macro is deprecated. You should use G_PRIORITY_LOW instead.
+This macro is deprecated. You should use %G_PRIORITY_LOW instead.
</para></note>
</para>
GTK_TYPE_WIDGET);
}
+/**
+ * gtk_container_child_type:
+ * @container: a #GtkContainer.
+ *
+ * Returns the type of the children supported by the container.
+ *
+ * Note that this may return %GTK_TYPE_NONE to indicate that no more
+ * children can be added, e.g. for a #GtkPaned which already has two
+ * children.
+ *
+ * Return value: a #GtkType.
GtkType
gtk_container_child_type (GtkContainer *container)
{
* @border_width: amount of blank space to leave <emphasis>outside</emphasis> the container.
* Valid values are in the range 0-65535 pixels.
*
+ * Sets the border width of the container.
+ *
* The border width of a container is the amount of space to leave
* around the outside of the container. The only exception to this is
* #GtkWindow; because toplevel windows can't leave space outside,
GTK_PRIVATE_UNSET_FLAG (container, GTK_RESIZE_PENDING);
}
+/**
+ * gtk_container_set_resize_mode:
+ * @container: a #GtkContainer.
+ * @resize_mode: the new resize mode.
+ *
+ * Sets the resize mode for the container.
+ *
+ * The resize mode of a container determines whether a resize request
+ * will be passed to the container's parent, queued for later execution
+ * or executed immediately.
+ **/
void
gtk_container_set_resize_mode (GtkContainer *container,
GtkResizeMode resize_mode)
return container->resize_mode;
}
+/**
+ * gtk_container_set_reallocate_redraws:
+ * @container: a #GtkContainer.
+ * @needs_redraws: the new value for the container's @reallocate_redraws flag.
+ *
+ * Sets the @reallocate_redraws flag of the container to the given value.
+ *
+ * Containers requesting reallocation redraws get automatically
+ * redrawn if any of their children changed allocation.
+ **/
void
gtk_container_set_reallocate_redraws (GtkContainer *container,
gboolean needs_redraws)
gtk_signal_emit (GTK_OBJECT (container), container_signals[SET_FOCUS_CHILD], widget);
}
+/**
+ * gtk_container_get_children:
+ * @container: a #GtkContainer.
+ *
+ * Returns the the container's non-internal children. See
+ * gtk_container_forall() for details on what constitutes an "internal" child.
+ *
+ * Return value: a newly-allocated list of the container's non-internal children.
+ **/
GList*
gtk_container_get_children (GtkContainer *container)
{
chain);
}
+/**
+ * gtk_container_set_focus_chain:
+ * @container: a #GtkContainer.
+ * @focusable_widgets: the new focus chain.
+ *
+ * Sets a focus chain, overriding the one computed automatically by GTK+.
+ *
+ * In principle each widget in the chain should be a descendant of the
+ * container, but this is not enforced by this method, since it's allowed
+ * to set the focus chain before you pack the widgets, or have a widget
+ * in the chain that isn't always packed. The necessary checks are done
+ * when the focus chain is actually traversed.
+ **/
void
gtk_container_set_focus_chain (GtkContainer *container,
GList *focusable_widgets)
* no additional reference count is added to the
* individual widgets in the focus chain.
*
- * Retrieve the focus chain of the container, if one has been
- * set explicitely. If no focus chain has been explicitely
+ * Retrieves the focus chain of the container, if one has been
+ * set explicitly. If no focus chain has been explicitly
* set, GTK+ computes the focus chain based on the positions
* of the children. In that case, GTK+ stores %NULL in
* @focusable_widgets and returns %FALSE.
*
- * Return value: %TRUE if the focus chain of the container,
- * has been set explicitely.
+ * Return value: %TRUE if the focus chain of the container
+ * has been set explicitly.
**/
gboolean
gtk_container_get_focus_chain (GtkContainer *container,
return container->has_focus_chain;
}
+/**
+ * gtk_container_unset_focus_chain:
+ * @container: a #GtkContainer.
+ *
+ * Removes a focus chain explicitly set with gtk_container_set_focus_chain().
+ **/
void
gtk_container_unset_focus_chain (GtkContainer *container)
{
* @child: a child of @container
* @event: a expose event sent to container
*
- * When a container receives an expose event, it must send synthetic
+ * When a container receives an expose event, it must send synthetic
* expose events to all children that don't have their own #GdkWindows.
* This function provides a convenient way of doing this. A container,
* when it receives an expose event, calls gtk_container_propagate_expose()
*
* In most cases, a container can simply either simply inherit the
* ::expose implementation from #GtkContainer, or, do some drawing
- * and then chain to the ::expose implementation from GtkContainer.
+ * and then chain to the ::expose implementation from #GtkContainer.
**/
void
gtk_container_propagate_expose (GtkContainer *container,
projects / gtk4.git / commitdiff